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jNTRODUCTION 

Multics conventions currently forbid subroutines which may 
be called by many different programs from performing output 
unless that is their primary purpose* The reason for this rule 
is the "principle of transparency*" which requires that the 
subroutine be usable in environments which do not have standard 
I/O attachments* and In environments which wish to use the 
subroutine without obtaining any output. In particular* 
subroutines are currently forbidden to use com_err_ to report 
status. The standard method for reporting status is to supply an 
additional argument to the subroutine which will be set to zero 
or to a standard status code by the subroutine. 

The caller of such a subroutine must have some knowledge of 
the cases In which status codes are returned. Often* the calling 
program has the choice of including a series of tests for each of 
the possible statess recognized by the subroutine* or of simply 
assuming that any nonzero status code Indicates that the routine 
failed. Mhen a status code is returned* the calling program 
often wishes to produce a message describing the situation. But 
in some cases* the subroutine can recognize so many different 
situations that the calling program will be unable to produce a 
helpful message without additional communication between the 
calling program and the subroutine. This problem was encountered 
In the design of delete,.* when deleting a directory. If a 
directory contains Items which cannot be deleted* there is 
currently no clean way to Inform the caller of delete, of the 
pathname of the item. 

Subroutines which can detect multiple errors (such as 
compilers) have an even more difficult problem. The returning of 
a status code is suited only to the detection of single errors. 
Requiring the calling program to allocate storage for a usually 
null array of status indicators or status messages seems 
uneconomical* and saving the messages in storage allocated by 
the subroutine encounters other problems If multiple invocations 
of the routine may exist in the same process. 

Multlcs Project internal working cocumentation. Not to be 
reproduced or distributed outside the Hut tics Project. 
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Hhen we thlnl* of small subroutines* tike square root 
programs* these problems can be Ignored or papered over. But 
when large subsystems are used as subroutines of user application 
programs* the need for a mechanism which allows subroutines and 
subsystems to report status in detail* while still allowing the 
calling environment control over the actual output and the 
content of the message* becomes more and more important. 



RRflPQSAL 

To accomplish these coals* a new subroutine is proposed* 
called sub_err_» which will be usee by subroutines in much the 
same way that co»_err_ is used by commands. Draft HPH SHG 
documentation is attached. (The "sub" can be considered to be a 
contraction of either "subroutine" or "subsystem.") A call to the 
subroutine might look like this! 

call sub_err_ fcode* "sort"* infop* "c"* retval* 
"Input record "d ignored."* record_nol ? 

Hhen sub_err_ is called* the format string is assembled in the 
same way that ioa_ does it* a structure is filled in* and the 
condition 

sub_error_ 

Is signalled. Unlike the call to com_err_* however* sub_err_ 
does not print the message on return from the signal* it assumes 
that the environment has disposed of the message. 

The default_error_handler_ for standard Multlcs processes 
will in fact currently print out such a message. However, the 
format of the message currently produced should be improved 
slightly* so that it looks something like this* 

name error by callername I location.. 
Com_err string. Ioa_ formatted string. 

(The message returned by com_err_ for small integer codes should 
also be changed from "Code l not found in error_table_" to Just 
"Code 1".} For example* the call above might produce the message 

sort error by sort_I123<» ( bound.. sort..! 56771 
Record too short. Input record 33 1 * ignored. 

The sort routine could use sub_err_ as a way of printing a 
message; or* by adding code which tested the value of r fttyat * it 
could allow the user the chance to Intercept the error and 
specify* for example* that the record be padded out with blanks. 
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The use of the * 
which wish to intercept 
alternative action to 
will set retval to zero, 
future extension to the 



retval" argument 
the s ub_e rr or _ 
the subroutine* 
It might be 
start command so 



is to allow environments 
condition and specify 
The standard environ sent 
possible to propose a 
that the command 



start -return 7 



would locate the condition Information structure* set retva l to 
7* and return to sisnal_* 

The Introduction of the sub_error_ condition is in fact a 
concealed Incompatible change for those users who have their own 
default error handlers* since it now becomes a requirement that 
the handler for sub_error_ understand the ™no_pause M switch and 
b«> able to dispose of the output message. The Hey step is the 
Introduction of a n*M principle* obverse to the principle of 
transparency* which is that every process ought to have a handler 
of last resort* 



Alt subroutines which call sub_err_ should 
noted in their documentation* showing the name 
used in each possible call and the action taken 
whatever values of retval are allowed* 



have the fact 

and code values 

on return with 



Programs which have a handler for sub_error_ must check the 
condition information structure and be prepared to pass signals 
on if they cannot handle them. 
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Nam e! sub_err_ 

This program Is called by subroutines which which wish to 
report an unexpected situation. The subroutine specifies an 
identifying message and may specify a status code* Switches 
which describe whether and how to continue execution and a 
pointer to further Information may also be passed to sub_err_* 
The environment which Invoked the subroutine caller of sub_err_ 
may intercept and modify the standard system action taken when 
sub_err_ is called* 



!LSJ3£« 

del sub_err_ entry options (variable); 

call sub_err_ (code* name* flags* infop* retval* 
ct l_string* loa_args); 



where 
1) code 



is a status code describing the reason for 
calling sub_err_. code should be declared 
fixed bin (39). (Input) 



2) name 



is the name of the subsystem or module on 
whose behalf sub_ err_ is called* name should 
be declared as a nonvarylng character string* 
(Input) 



3) flags 



describe how and whether restart may be 
attempted* Flags shoulc be declared as a 
nonvarylng character string. (Input) 



The following values are permlttedt 



■c" 

•r 



continue after printing message, 
fatal error. No restart allowed. 



k) infop 



is an optional 
specific to the 
system environment 
but It is provided 



pointer to Information 
situation* The standard 

does not use this pointer* 
for the convenience of 



other environments* infop 
aligned pointer. (Input) 



should be an 



51 retval 



is a return value from the environment to 
which the error was reported* The standard 
system environment sets this value to zero* 
Other environments may set retval to other 
values* which may be used to select recovery 
strategies. retval should be declared fixed 
bin (35). (Input/Output) 
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6) ctl_string 



71 loa.args 



is an ioa_ format control string which 
defines the message associated with the call 
to sub_err_. Consult the description of loa_ 
In AG93. ctl_string should be declared as a 
nonvarying character string. (Input) 

are any arguments required for conversion by 
ctl_string. (Input) 



Operation 

Sub_err_ proceeds as foltowsi the structure described below 
is filled in from the arguments to sub_err_, and the system 
subroutine signal_ is called to raise the "sub_errQr_" condition. 



a sub_error_ 



When the standard system environment receives 
signal* it prints a message of the format 

name error by subrnamel location 

Status code message. Message from ct lustring. 

The standard environment then sets retval to zero and returns* if 
"c" was specified? otherwise it calls the listener. If "start" 
is typed* the standard environment will return to sub_err_, which 
will return to the subroutine caller of sub_err_ unless "f" was 
specified. If "f" was specified* sub_err_ will signal 
"1 1 legal_return." *" 



Use fey Subsystems 



If an application program wishes to call a subsysten which 
may report errors by sub_err_, and wishes to replace the standard 
system action for some classes of sub_err_ calls* the application 
should establish a handler for the "sub^error.." condition by a 
PL/I ON-statement. When the handler is activated as a result of 
a call to sub_err_ by some dynamic descendant* the handler should 
call flnd_condition_info_ to obtain the "sof tware_inf o_ptr" which 
will point to a structure with the following declaration. 



del 



info aligned based (sof tware_inf o_ptr) * 

length fixed bin* 

version fixed bin* 

action_f lags aligned* 

3 cant_r«start bit (II unal* 

3 defaul 1_restart bit (1) unal* 

3 pad bit (3<»> unal* 

info__string char (256) var* 

code fixed bin (35)* 
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2 retval f ixed bin 
2 name char C32> * 
2 infop ptr; 



(35) 



where 

length 

version 

cant_restart 
defaul t_restart 

pad 

inf o_string 

code 
retval 

name 

lnfop 



is the size of the structure in words. 

is the version number of the structure. 
This is version 2, 

is "i"b if the condition cannot be 
restarted. 

is "i M b if the standard environment will 
print the message and continue execution 
without calling the listener. 

is padding 

is the converted message from ct t_string 
and ioa_args. 

is the status code. 

is the return value. The standard 
environment sets this value to zero. 

is the name of the module encountering 
the condition. 

is a pointer to additional information 
associated with the condition. 



The handler should chech lnfo.name and Info. code to make sure 
that this particular call to sub_err_ is the one desired* 8nd if 
not call contlnue_to_slgnal_. If the handler determines that it 
wishes to intercept this call to sub_err_, the info structure 
will provide the message as converted, switches, etc. Any change 
made to the value of info. retval will be returned to the caller 
of sub_err_ if control returns to sub_err_« 



